MacMiNT Architecture Summary

MacMiNT is composed of 2 main programs: JET and MiNT.  JET (Just
Enough TOS) is a Mac application that installs interrupt, exception,
and trap handlers to make the Mac look like an Atari running TOS.  JET
loads MiNT which adds multi-tasking and other UNIX like features to
TOS (or JET in this case).  This document describes some of the
handlers that JET uses to pretend the Mac is an Atari.

The most essential emulation of TOS is in trap handling.  JET installs
handlers for traps 1, 13, and 14 to handle DOS, BIOS, and XBIOS calls
(note 1).  These traps are called by TOS programs by putting a short
value on the stack indicating what OS function is requested, followed
by the parameters for that function.  The trap dispatchers use this
value to index into an array of functions to handle each request.  JET
only has handlers for functions used by MiNT.  Most other functions
are handled by MiNT. When a program running under MiNT make a trap
call, it often involves trapping in to MiNT, JET, and the Mac Toolbox.
All of this trap overhead is the main reason for the slowness of
MacMiNT relative to what you would expect on an Atari.  The speed of
the Macs relative to the Atari's helps to balance the problem out.
See Atari/Programming/gemdos.arc for more info on TOS functions.

MiNT multitasking is provided for by installing a context switching
function in the VBL (vertical blanking) interrupt handler (mint:
main.c, intr.s, context.s, timeout.c).  JET sets up a VBL routine and
a level 1 interrupt handler to dispatch to the MiNT VBL handler (jet:
vector.c, intr.c).  The VBL routine sets a flag that the interrupt
handler watches for.  Normally the interrupt handler just returns to
the code that was interrupted, but if the flag has been set (every
1/60th second), then the MiNT VBL is invoked.  JET also installs
TimeManager routines that go off every 20ms and 5ms to support the
other interrupts that MiNT expects.  The 20ms timer is used to
maintain a system time keeping value.  All other interrupts are
handled by the MacOS and are converted into the standard MacOS events
like mouseDown, keyDown, etc.

There is one MiNT process that gets built into the MiNT kernel (mint:
main.c) whose only job is to repeatedly call a function that allows
JET to process MacOS events.  MacOS events are processed with
WaitNextEvent to allow other applications to get CPU time.

JET doesn't really install exception handlers.  It does save the
original exceptions handlers, though, because MiNT installs some of
its own exception handlers.  The main ones are bus error, address
error, illegal instruction, divide by zero, and trace.  These
exceptions are turned into signals that are sent to the MiNT process
that caused them.  The handling of these exceptions by MiNT make it
possible to support debuggers like GDB.

JET installs its vectors before it passes control to MiNT and
de-installs them when control is passed back from MiNT.  Because the
vectors are not installed while JET is in control, it is possible to
debug JET using standard debugging tools like THINK C's debugger and
Macsbug.  It is possible for JET to loose control of the CPU when it
calls WaitNextEvent.  If JET didn't remove its vectors, then other
programs that messed around with these vectors might not work.  It is
possbile to run two copies of JET because it was designed to be
multi-finder friendly.

The functions for installing and removeing the vectors are included in
the sysvar data structure so that they can be called from MiNT and by
programs running under MiNT.  They are called put_vector and
pull_vector.  If you are going to call Mac Toolbox routines, it is
safest if you enter supervisor mode to prevent process pre-emption and
call pull_vector to allow Macsbug to work and avoid any problems if
MacMiNT looses the CPU.

Brad Pickering brad@tazboy.jpl.nasa.gov

PS - Please let me know if you know how to make this clearer or more
complete.

notes:

1.  Macsbug uses traps 13 and/or 14 to support stepping through
instructions.  This functionality of Macsbug can not be used when JET
has its handlers installed.